═══ 1. Introduction ═══ REXX Code Formatter/2 is a full-function REXX code formatter written in REXX and using the facilities of VisPro/REXX and VisPro/Reports. The purpose of this program is to provide users with the ability to format their REXX programs in a style that best suits their desires. While it is possible that some user's may wish to format their code in a manner not accommodated by RCF/2, most user's should find that this program will handle their needs. For more on the facilities provided by REXX Code Formatter/2 and how to use it, see: Description Configuring RCF/2 Formatting a REXX Source Program ═══ 1.1. Limitations ═══ The REXX Code Formatter/2 is not a syntax checker or code preprocessor. It assumes that the program being formatted is a reasonably checked program, and it follows the general rules of REXX coding. While it can, by the nature of its processing of the REXX statements, detect certain errors, such as a Do or Select statement without a corresponding End statement, it is not the purpose of RCF/2 to find coding errors. It may be possible to code a REXX program in a highly unconventional manner such that RCF/2 will not properly format a REXX statement. Such deficiencies should be reported to RKE Consulting, Inc., and every effort will be made to provide for the desired coding preference. RKE Consulting, Inc. does not guarantee that all coding styles will be handled, and no warranty of future corrections or additions to handle all coding styles is implied or should be assumed. Since the possible styles of coding REXX programs is almost unlimited, it is possible that some styles may not be completely handled by RCF/2. However, within reason, and based on the viability of this product, every effort will be made to accommodate the desires of the users of RCF/2. Notices Registration ═══ 1.2. Support ═══ Technical Support Support for RCF/2 is provided to all registered users. Questions and problems should be sent via E-mail to rkeinc@ibm.net, or faxed to RKE Consulting, Inc. at 281-370-9842. Please write in English, and include a return address where we may respond. Errors If you believe that you have found a defect in RCF/2, please report it to Technical Support at the E-mail address given above. To report an error, please send a copy of the code that fails to format correctly, either as an attachment to the note or in the note using cut and paste. Include a description of the error, noting where the program fails to properly format, and the configuration settings used. Please to not FAX a copy of the program. Enhancement Suggestions for improvements and additional features are welcomed. Subject only to the reasonable acceptance of this product, and the resulting viability, all such suggestions will be carefully considered and, when possible, added to RCF/2. Send all suggestions and requests via E-mail to rkeinc@ibm.net, or mail them to RKE Consulting, Inc. P.O. Box 11569 Spring, TX 77391-1569 ═══ 1.3. Notices ═══ Every effort has been made to insure that this program runs as documented, but RKE Consulting, Inc. is in no way liable or responsible for any loss of time or data associated with the use of this product. OS/2 is a registered trademark of International Business Machines. VisPro/REXX and VisPro/Reports are trademarks of HockWare, Inc. ═══ 2. Description ═══ REXX Code Formatter/2 was developed to address three important areas of program development: Consistency of Style, Maintained and Inherited code, and Final Documentation Consistency of Style All programmers, novice or professional, develop a style of coding that they like to use when writing a program. Often times, however, in the haste to complete a program, or simply because they are concentrating on the logic and not the format, the style used is not always consistent. For example, comments are not aligned alike for easier reading and statements under a DO or SELECT are not properly or consistently indented. Maintained and Inherited Code Some programs are inherited and some contain code that was included from other sources. In both cases, the style is often different, and in some instances, very different from that used by the person maintaining the code. A program with the END statement aligned with the other code under a DO statement is very difficult to maintain by a programmer used to having the END align with the DO statement, itself. Final Documentation Finally, when a person has completed a program and wants to turn it over to maintenance, give it to the customer for whom it was done, or simply show to others, there is a natural desire, if not a need, to make it neat, consistent, and professional looking. Even the best of programs can look a bit sloppy if functions and REXX keywords are sometimes in one case and sometimes in another. Time does not always allow programmers to go back over their work to "clean" it up, and even when there is time, the task, by its nature, is a very boring one, and all inconsistencies are seldom removed. The purpose of REXX Code Formatter/2 is to handle this formatting chore for the programmer. RCF/2 has been written to allow a wide range of programming styles (and even ones we probably have never heard of). ═══ 2.1. The Main RCF/2 Window ═══ All the work done with REXX Code Formatter/2 occurs using the main RCF/2 window. Below is a sample of an RCF/2 window after it has processed a REXX source program file using a style defined by the programmer. Note: To get a brief description of the purpose of the various parts of this window, point and click to the area of interest. ═══ 2.2. Formatting a REXX Source Program ═══ To format a REXX source program, you must do the following: 1. Configure RCF/2 according to the style of formatting desired. 2. Identify the REXX source file to be formatted. 3. Activate the formatting facility of RCF/2. The first step is done usually once. Some times the defaults meet with the user's desires, and formatting a program may begin immediately, but you should review the RCF/2 configuration just to be sure it does, indeed, satisfy you needs. The other two steps are performed as needed. Afterwards you may print a listing of the formatted program, save the formatted program, edit it, or reformat it. ═══ 3. Configuring RCF/2 ═══ RCF/2 allows you to configure it according to your style of coding. Configuring RCF/2 is not done often since a user's style changes slowly over time, if at all. At most, you should find that you will alter your RCF/2 configuration based on a project or major application. For whatever reason, defining or changing the configuration of RCF/2 to match your style is easy. To configure RCF/2, open the configuration notebook by doing the following: 1. Click on Configure on the RCF/2 main window menu bar. 2. Click on Settings on the resulting pull-down menu. After opening the configuration notebook, make any changes desired and close the notebook by clicking on the Save, Exit, or Cancel button at the bottom of the notebook page. ═══ 3.1. Configuration Notebook Options ═══ The configuration notebook allows you to define how you want your REXX programs formatted. The notebook is divided into: General These are the formatting parameters that apply to the general formatting of the input program, such as whether you want to split lines at semicolons or edit out redundant spaces. Indentation This part of the configuration notebook defines how much indentation you want for different types of statements. For example, Indentation can occur from such things as the nesting of statements under a Do or Select and because of a statement continuation. Format You may define how the various symbols in the program, such as variable and function names, are to be formatted. Comments RCF/2 allows you to define how your various types of comments are to be formatted. This part of the configuration notebook defines your preference for comment alignment. Special In this section, you may select some special formatting options that do not fall into the normal REXX formatting capabilities. ═══ 3.1.1. General Settings ═══ The General Settings page of the configuration notebook allows you to define some general rules about the formatting of REXX source programs and the behavior of RCF/2. General Editing The General Editing options pertain to the overall editing. They are options that apply to the general look of the formatted program and the general behavior of RCF/2 when editing a REXX program. Split lines at semicolons When this box is checked, any semicolons found in a REXX statement will cause the semicolon to be dropped and the text following the semicolon to start a new line. Edit Spacing RCF/2 will attempt to keep the same spacing of the source text. However, if this box is checked, multiple blanks in a REXX statement will be reduced to a single blank unless such blanks are needed for indentation and comment alignment, or they are contained within a comment of literal string. Start new line with keywords Then or Else When this box is checked, any Then or Else keywords found which at not already the first REXX program statement word on a line will cause a new line to be started with the found Then\Else keyword. Start new line after keywords Then or Else When this box is checked, any program statement text that follow Then and Else keywords will begin on a new line. Indent Keyword End By default, End keyword statements are indented the same amount as the corresponding Do or Select statement. Checking this box, however, causes the End keyword statements to be aligned with the same indentation as the other statements under the corresponding Do and Select. Ignore any comment alignment problems It is possible that, in spite of what RCF/2 may "say" about comment alignment problems, the resulting alignment is satisfactory to you, or for the time being, you may want to concentrate only on code formatting problems. For whatever reason, you may ask RCF/2 not to display any comment alignment problems by checking this box. Cross-reference While not a part of the formatting of a REXX program, RCF/2 is capable of gathering information about the formatted program as it is processed. For example, RCF/2 can record where a label, variable, or function is used. If you would like to find where a label, variable, or function is used, or you want to print a cross-reference listing for one of these types of REXX symbols, you should check the appropriate box on this page of the configuration settings. Labels RCF/2 will record and make available a list of all the labels in the formatted program and the line number where each label is defined. Variables RCF/2 will record and make available a list of all the variables in the formatted program, and it will include a list the line numbers where each of the variables are referenced. Functions RCF/2 will record and make available a list of all the functions referenced in the formatted program, and it will include a list of the line numbers where each of the functions are referenced. Note: A call to a labelled statement in the program is treated as a call to a function. Because RCF/2 is a one-pass formatting program, it cannot always recognize a call to a function as being, in reality, a call to a labelled statement. For consistency, RCF/2 treats all calls or function invocations as function references, whether or not they are actually references to a labelled statement. ═══ 3.1.2. Indentation ═══ Use this page of the RCF/2 configuration notebook to set the amount of indentation that is to occur when formatting a REXX program. General Indentation Unless otherwise noted in the configuration notebook settings, all statements in the REXX source program will be formatted beginning in column 1 plus the amount given here. Continuation indentation Continuation of a statement, explicitly noted by the use of a comma or implicitly when a line ends with Then or Else, will be indented by the current indentation plus the amount specified here. Indentation amount per Do/Select When a Do or Select statement is processed, the statements that follow, and are associated with that Do/Select, will be indented by the amount used for the Do/Select statement plus the amount specified here. Indentation for lines starting with Then/Else When a line begins with the keywords Then or Else, that line is indented by the current indentation amount plus the amount specified here. One-byte indentation threshold When a large number of nested Do and Select statements occur, the accumulated indentation may become large. If you wish, you may specify a "threshold" value here. Whenever the current indentation exceeds this amount, for all indentations beyond the threshold, one byte will be used instead of the amount specified above. ═══ 3.1.3. Formatting Options ═══ The Formatting Options pages of the configuration notebook allow you to specify how certain REXX symbols will be explicitly formatted. In particular, you may specify how to format the names of: REXX Keyword Instructions, Keywords,, Variables,, Functions, and Labels. ═══ 3.1.3.1. REXX Keyword Instructions & Variables ═══ This page of the Formatting Options allows you to specify how RCF/2 is to format REXX Keyword Instructions and Variable names. REXX Keyword instructions The top part of this Formatting Options page allows you to define how keyword instructions are to be formatted. No formatting No formatting will be performed on any REXX keyword instruction. They will appear on the resulting output exactly as they appear in the input source program. All lower case All REXX keyword instructions will appear entirely in lower case letters in the resulting output. Mixed case All REXX keyword instructions will appear as proper nouns. That is, the first letter will be capitalized and the other letters will be in lower case. All upper case All REXX keyword instructions will be appear entirely in upper case letters in the resulting output. Indent any unnested Return This option is meaningful only if the general indentation is not zero, and it only applies to Return statements that are not subordinate to some previous Do or Select statement. That is, when the Return occurs, there is no Do or Select statement that has not been completed by a corresponding End clause. If this box is checked, a Return statement will be indented by the general indentation amount. Otherwise, Return statements will be aligned on column 1 of the formatted output. Indent any unnested Exit This option is meaningful only if the general indentation is not zero, and it only applies to Exit statements that are not subordinate to some previous Do or Select statement. That is, when the Exit occurs, there is no Do or Select statement that has not been completed by a corresponding End clause. If this box is checked, a Exit statement will be indented by the general indentation amount. Otherwise, Exit statements will be aligned on column 1 of the formatted output. Variables The bottom part of this Formatting Options page allows you to define how variable names are to be formatted. No formatting No formatting will be performed on any variable name. They will appear on the resulting output exactly as they appear in the input source program. All lower case All variable names will appear entirely in lower case letters in the resulting output. Mixed case All variables will appear as proper nouns. That is, the first letter will be capitalized and the other letters will be in lower case. All upper case All variable names will be appear entirely in upper case letters in the resulting output. ═══ 3.1.3.2. Keyword Names Formatting ═══ Technically, the first clause of a keyword instruction begins with a keyword. For RCF/2, the initial keyword is handled by the formatting configuration given for REXX Keyword Instructions. The Keyword Names Formatting portion of the configuration notebook handles all the other keywords within a REXX keyword instruction. For example, If is formatted according to the configuration under REXX Keyword Instructions, while the formatting rules for Then and Else are defined here. No formatting No formatting will be performed on any REXX keyword. They will appear on the resulting output exactly as they appear in the input source program. All lower case All REXX keywords will appear entirely in lower case letters in the resulting output. Mixed case All REXX keywords will appear as proper nouns. That is, the first letter will be capitalized and the other letters will be in lower case. All upper case All REXX keywords will be appear entirely in upper case letters in the resulting output. In other words, they will appear as they normally do in REXX documentation. Sometimes it is desirable to have certain keywords in upper case and others in mixed case. For example, some programmers like the Then and Else keywords to be in mixed case while the VALUE keyword, in the Address and Signal REXX Instructions, to be in upper case. The bottom part of Keyword Names Formatting page of the configuration notebook allows you to specify Upper Case for all keywords of selected instructions. These specifications will override any specifications given above. To make all keywords upper case for the Address, Call, Numeric, Options, or Signal keyword instructions, check the corresponding box. ═══ 3.1.3.3. Function Names ═══ In REXX, functions may be external or internal, and when RCF/2 recognizes a function invocation it will format the function name according to the specifications noted in the Function Names Formatting and Function Names Sources pages of the configuration notebook. A number of formatting options are allowed, including the ability to have upper and lower case letters intermixed within the function name. For example, function names RxMessageBox, SysCurState, and MyFavoriteFunction are all possible. You can even have RCF/2 make note of the labels in your program, and on subsequent passes, format the calls to those routines to match the correspond label. (For more on this facility, see: Label Names Formatting.) ═══ 3.1.3.3.1. Function Names Formatting ═══ How function names are to be formatted is specified on this and the following page of the RCF/2 configuration notebook. Default Format The top portion of this configuration notebook page defines how all function names are to be formatted by default. That is, the formatting rules to be used for all function names not identified elsewhere. Functions that are identified elsewhere are the REXX Built-In Functions, below, and those specified through Other Function Names Sources. No formatting No formatting will be performed on a function name. They will appear on the resulting output exactly as they appear in the input source program. All lower case All function names will appear entirely in lower case letters in the resulting output. Mixed case All function names will appear as proper nouns. That is, the first letter will be capitalized and the other letters will be in lower case. All upper case All function names will be appear entirely in upper case letters in the resulting output. Notify if function name unknown In addition to being able to format function names not identified elsewhere, you may request that you be notified if such a function name occurs. That is, you can ask that you be told when a function name occurs that requires use of the default formatting rule. To activate this feature, check this box. REXX Built-In Functions RCF/2 includes a built-in list of the standard REXX functions, function names such as ABBREV, DATATYPE, LINEIN, or SUBSTR which are part of the defined REXX language. The bottom portion of this configuration notebook page defines how all of these particular function names are to be formatted. No formatting No formatting will be performed on any of these function names. They will appear on the resulting output exactly as they appear in the input source program. All lower case All standard REXX function names will appear entirely in lower case letters in the resulting output. Mixed case All standard REXX function names will appear as proper nouns. That is, the first letter will be capitalized and the other letters will be in lower case. All upper case All standard REXX function names will be appear entirely in upper case letters in the resulting output. ═══ 3.1.3.3.2. Other Function Names Sources ═══ Many REXX programs include the use of functions that are not part of the standard REXX language. RCF/2, as an example, makes use of functions provided by the REXXUTIL functions provided as part of OS/2 Warp. This page of the configuration settings notebook allows you to ask RCF/2 to format these additional function names according to a given specification or by their respective documentation. Built-in Formats Some REXX functions are well known, and RCF/2 provides for these functions explicitly so that you need not expend the effort to define them using the Additional Function Names procedure described below. To specify that RCF/2 should format these function names, if found, according to their documentation, check the appropriate box. Note: If you wish to format the associated functions differently from the documentation and the default, you may still do so using the Additional Function Names procedure described below. RexxUtil All of the REXX Utility Functions defined in The OS/2 Procedures Language 2/REXX documentation will be formatted according to the format given in the on-line documentation table of contents. (These are the functions that, except for RxMessageBox, begin with Sys, such as SysCls and SysCopyObject.) RxUtil All of the miscellaneous REXX utility functions defined in RxUtils documentation (RxUtils version 1.73) will be formatted according to the format given in the on-line documentation table of contents. (These are the functions that begin with Rx, such as RxAddGroup and RxAddProgram.) VisPro/REXX All of the REXX functions defined in VisPro/REXX (version 3.0) and VisPro/Reports (version 2.0) are formatted according the HockWare, Inc. documentation provided for those programs. In addition to, or in place of, the default formatting and REXX functions formatting defined on the Function Names Formatting page of the configuration notebook, and the Built-In formats noted above, you may specify up to three files that contain a list of function names that are in the format to be used. When RCF/2 finds a function name in a program that matches one of the function names in a provided file, it will format the function name to match that given in the file. Thus, if "MyFunction" appears in one of the specified function names files, any reference to "myfunction," for example, would become a reference to "MyFunction." In addition to specifying the function names file, you may specify whether the file is to be used. This option is provided to speed look-up processing if a large function names file is not referenced for a given program. Note: The option to use a file is automatically turned OFF if, at a later time, RCF/2 is invoked and the function name file no longer exists. Use associated label file If you have created an Associated Label Names File using the Create associated label names file option (see: Label Names Formatting), you may specify that this file be used as a Function Names Source. Additional Function Names To use this feature of RCF/2, do the following: 1. Enter the fully qualified name of the function file to be used, or click on the "Find..." button to locate the file to be used. 2. If the named file exists, the Use this file box will become active, and you may indicate if it is desirable to begin using the file. ═══ 3.1.3.3.2.1. Function Names File Format ═══ A function names file is a simple flat file containing a list of names of functions as they are to appear when used to format a function name in a source program. Each record in this file either contains one or more function names, separated by one or spaces, or it is a comment. Any record in the file that begins with an asterisk (*) is considered a comment, and such a record may contain any alphanumeric character that appears normally on a keyboard. Any record not starting with a asterisk is considered to contain one or more function names. All such names must conform to REXX function naming rules. A Function Names File may be stored anywhere on your system since the fully qualified name of the file is required by RCF/2. ═══ 3.1.3.4. Label Names Formatting ═══ Like other types of symbols processed by RCF/2, labels may also be formatted. In addition, you may check for duplicate labels, offset labels to the general indentation, and force all labels to start a new line. Labels The first part of the Label Names Formatting configuration defines how labels, themselves, will appear. No formatting No formatting will be performed on any label. They will appear on the resulting output exactly as they appear in the input source program. All lower case All labels will appear entirely in lower case letters in the resulting output. Mixed case All labels will appear as proper nouns. That is, the first letter will be capitalized and the other letters will be in lower case. All upper case All labels will be appear entirely in upper case letters in the resulting output. Label Names File If you would like to format all the references to the labelled statements in your program, you may ask RCF/2 to create a Label Names File. When such a file exists, and it is used (see: Other Function Names Sources), all calls or invocations to labelled statements will have the same format as the label itself. Update associated label names file Check this box to create or update a label names file with the label names contained in the program being formatted. If no label names file exists, it will be created. If a label names file exists, it will be updated. File Name In the space provided, enter the fully qualified name of the label names file to be created. If no name is specified or the Use this file box is not checked, RCF/2 will create a file that is:  In the same directory as the program being formatted,  Has the same file name as the program being formatted, and  Has a file extension of RFL. Note: A file name is not required. The ability to specify a file name is provided for those situations where: 1. You want the label names file to reside in another directory, or 2. You wish to create a label file that has the labels from more than one program. This capability is important if you are developing a VisPro/REXX application or a library of individual REXX program. Find... You may enter the name of the label names file, or you may click on the Find... button to locate the file to be used. Once a file name has been entered, the Use this file button will become active, and it may be selected. Use this file Check this button if you wish RCF/2 to use this file to record labels found in the formatted program. Note: As mentioned above, if this option is not checked and the Update associated label names file is, the default file name will be used, regardless of the presence of any given file name. Additional Processing The last part of the Labels Name Formatting configuration defines additional processing options for labels. Check for duplicate labels RCF/2 will notify you, at then end of formatting, if any duplicate labels were found in the processed REXX source program. Align labels on general indentation Normally, labels are aligned beginning in the first column of the generated output. If this box is checked, the labels will be aligned according to the specification of the general indentation. Note: This option is only meaningful when the general indentation is greater than zero. Begin all labels on a new line This option allows you to specify that if more than one label appears on a line, each label after the first should begin a new line. For example, if the input REXX program contained: LABEL1: LABEL2:LABEL3: The resulting output would become: LABEL1: LABEL2: LABEL3: No space between label and colon Although it is customary for a label to be followed by a colon with no intervening spaces, it is not a requirement of the REXX language. To insure that this convention is followed, or to change from a convention where there is one or more spaces following the label name, this box should be checked. ═══ 3.1.4. Comments ═══ There are three types of comments in a REXX program that are recognized by RCF/2: 1. Full-line, 2. Left-hand, and 3. Right-hand. A full-line comment is a comment that takes up the entire source file record. There may be requirements to indent such comments, but if one comment, or a continuation of a comment, is the only thing in a given program source record, it is considered a Full-line comment. A left-hand comment is a comment that, with the exception of spaces, is the first REXX element to begin a source program line, and it is followed by something other than spaces. (If it were not followed by something, it would be a full-line comment.) A right-hand comment is the opposite of Left-hand comments. It is a comment that is preceded by something other than spaces. It should be noted that a comment could be both preceded and followed by something other than spaces. In RCF/2, if this occurs, the comment is treated in-line and has no special formatting other than that given any REXX program string being formatted according to the current specifications. Conversely, it is possible to have both left-hand and right-hand comments on the same line. RCF/2 can handle this, but the user may find that the lines in the program will be too long and unwieldily to provide a reasonably "readable" program. ═══ 3.1.4.1. Full-line Comments ═══ To define how full-line comments are to be aligned, you must specify the left and right alignment requirements for the comment. Full-line Comments Left Indentation. The left-hand alignment of a full-line comment is control by the type of indentation you select. No Action If this option is selected, any full-line comment will be written out in the same form and with the same indentation as found in the source program. No indentation All full-line comments will be left justified. Conditional Indentation If the comment in the input source begins in column 1, it will be formatted to begin in column 1 in the output. In all other cases, the comment will be formatted to align with the current indentation. Always use current indentation All comments will be aligned according to the current indentation. Full-line Comments Right Alignment The right-hand alignment of a full-line comment is control by the type of alignment you select. No Action If this option is selected, any full-line comment will be written out with the same alignment as found in the source program. Same as right-hand comments All full-line comments will have the same right-hand alignment as that specified for right-hand comments. Align on column You may select a column value that will specify on what column the full-line comments are to be right-aligned. Use the scroll buttons to the right to select the column number to be used. Align with extension / truncation If you have selected Same as right-hand comments or Align on column for the right-hand alignment of full-line comments, you have the option of selecting some special processing called "extension or truncation" of special full-line comments. This option is of particular interest to those that like to "box" their comments. If a full-line comment needs to be extended or truncated in order to meet the full-line comment right alignment specification, there is some additional processing that occurs. RCF/2 ignores any starting slash-asterisk and any ending asterisk-slash, and it looks at the remaining characters. If all the characters are the same, RCF/2 will extend or truncate the characters and adjust any slash-asterisk and asterisk slash as necessary. For example, assume the input data is as follows: Column--> 1 20 | | /*------------------------------*/ /* Comment */ /*-----------*/ If the alignment for full-line comments is 1 and 20, then the result will be: Column--> 1 20 | | /*----------------*/ /* Comment */ /*----------------*/ In other words the first comment line was truncated to align properly, and the third comment line was extended with the same character repeated so as to align according to the specifications. The middle comment, because it was not composed of a single character, simply had its asterisk-slash aligned. If the Align with extension / truncation box is checked, all full-line comments will be truncated or extended in the manner described above. The following options only apply to full-line comments that do not terminate with a final asterisk-slash. That is, they are comments that are continued on the following statement. Full alignment If a full-line comment does not terminate with a slash-asterisk, and it is composed of only one character, the character is repeated or truncated so that the final occurrence of the character is on the right-hand alignment column specification. For example, if the input looked as follows: Column--> 1 20 | | /*------------------------------- Comment -------------*/ The result would be: Column--> 1 20 | | /*------------------ Comment -----------------*/ One-short alignment Any extension or truncation of a full-line comment composed of the same character would be one short of full alignment. Using the example above, the result would be: Column--> 1 20 | | /*----------------- Comment -----------------*/ Two-short alignment Any extension or truncation of a full-line comment composed of the same character would be two short of full alignment. Using the example above, the result would be: Column--> 1 20 | | /*---------------- Comment -----------------*/ ═══ 3.1.4.2. Left and Right-hand Comments ═══ To define how left and right-hand comments are to be aligned within a given REXX program, select one option from each of the two types of comments listed. Left-hand Comments A left-hand comment is a comment that is preceded by, at most, spaces, and it is followed by some other REXX object such as a REXX statement or another comment. No Action If this option is selected, any left hand comment will be written out in the same form and with the same indentation as found in the source program. No indentation All left-hand comments will be left justified. General indentation All left-hand comments will be aligned according to the general indentation specification as defined under the Indentation page of the configuration notebook. Left and right alignment All left-hand comments will be aligned according to the specification given in the Starting column and Ending column values. Starting column Use the scroll buttons to raise or lower the value to be used for the column where left-hand comments are to begin. Ending column Use the scroll buttons to raise or lower the value to be used for the column where left-hand comments are to end. Note: If you use this option, consider the value that you assign to the General Indentation. A General Indentation that is less than the Ending column may not give you the results that you want. Right-hand Comments A right-hand comment is a comment that is preceded by some other REXX object, such as a REXX statement or another comment, and is not followed by anything except, at most, spaces. No Action A right-hand comment will be treated as a text string, and no formatting will occur except as required to accommodate the text preceding it. Left alignment All right-hand comments will be formatted to begin on the column specified for the starting column as specified in the Starting column value at the bottom of the Right-hand Comments box. The right-hand alignment for all right-hand comments will be set as needed based on the amount of text in the comment. That is, the ending asterisk-slash will be placed one space beyond the last non-blank comment text character. Right alignment All right-hand comments will be formatted to end on the column specified for the Ending column value at the bottom of the Right-hand Comments box. Note: When right alignment is elected, RCF/2 will, if space permits, automatically insert a blank between the last non-blank character and the terminating slash-asterisk. Left and right alignment All right-hand comments will be aligned according to the specification given for in the Starting column and Ending column values. Starting column Use the scroll buttons to raise or lower the value to be used for the column where right-hand comments are to begin. This value will be used if you have elected "Left alignment" or "Left and right alignment." Ending column Use the scroll buttons to raise or lower the value to be used for the column where right-hand comments are to end. This value will be used if you have elected "Right alignment" or "Left and right alignment." ═══ 3.1.5. Special Options ═══ Commented Line Numbers Unlike some programming languages, such as COBOL, REXX does not have a specific place in each statement to include a line number. However, because any REXX error message references a record or line number, programmers find that it can simplify their debugging process if they can put the record number in each REXX statement. There exist programs which will record line numbers in a set of REXX statements in the form of comments, usually at the end of each statement. These "commented line numbers" do not affect the running of the program, and they can be useful in locating the statement when there is a problem. Because such commented line numbers often appear as the left or right-most comment in a statement, RCF/2 cannot format the "true" left-hand or right-hand comments. To allow for these "commented line numbers" and still format a program containing them, RCF/2 allows for the recognition and generation of such numbers in lieu of using a separate program. To generate or remove commented line numbers, the user should do the following: Insert in column If a comment line number is to be inserted in a program, check this box. If this box is checked, use the scroll buttons to raise or lower the value to be used for the column where a commented line number is to start. Delete from column If a comment line number already exists and it is to be deleted from a program, check this box. You can also check this box if you plan to insert commented line numbers, and you may want to process the program again to renumber the lines. If the commented line numbers are not found in the location specified, no action is performed. If this box is checked, use the scroll buttons to raise or lower the value to be used for the column where a commented line number is to removed. Note: If commented line numbers already exist in the program, be sure to delete them, even if you plan to insert them. RCF/2 needs to delete any commented line numbers before it formats the REXX statement so that they do not get treated as normal comments. If you have requested "commented line numbers" be inserted, they will be added after the REXX statement has been formatted. ═══ 3.2. Closing the RCF/2 Configuration Notebook ═══ There are three ways that you may exit the configuration notebook processing: 1. You may close the notebook and save the settings so that they will be used immediately and in any future invocation of RCF/2. 2. You may ask for the notebook settings to be saved and used but any changes will last only for the current invocation of RCF/2. That is, if you made any changes, these changes will be dropped when RCF/2 is closed, and the settings that existed before the changes were made will be restored. 3. You may simply exit the notebook window and cancel any modifications made to the notebook while it was open. To close the configuration notebook using one of the above modes, select one of the buttons at the bottom of the configuration notebook page. Select: Save to exit the notebook window and save any modifications for use now and for any future invocation of RCF/2. Exit to exit the notebook window and save any modifications until RCF/2 is terminated. Cancel to exit the notebook window without saving any modifications. ═══ 3.3. Editor Specification ═══ RCF/2 provides for the user to edit the input program. By default, REXX Code Formatter/2 assumes the OS/2 E editor is available. You may, however, specify a different editor my adding it to your configuration. To do this, perform the following: 1. Click on the Configure menu item on the RCF/2 main window menu bar. 2. Click on Editor on the resulting pull-down menu. 3. Using the resulting dialog box, locate the editor to be used. 4. When the editor is located, double click on the name of editor, or click once on the editor name and then once on the OK button. Afterwards, you may then edit the input program using the defined editor by selecting the Action button on the menu bar followed by the Edit action on the resulting pull-down menu. Note: If you specify the name of the editor in the dialog box, directly, rather than locating it, you must specify the fully qualified name of the editor. RCF/2 will check the name given, and if the file does not exist as given, the Edit option will not be selectable on the Action menu. ═══ 4. Opening a REXX Source Program ═══ You must open the REXX source program that you wish to process. Once it has been opened, you may then format or edit it. To open a source program, do the following: 1. Select File from the RCF/2 main window menu bar. 2. Select Open from the resulting pull-down menu. 3. Using the dialog box, select the file to be processed. Note: The name of the selected file always appears just below the RCF/2 main window menu bar. If no name is shown, no formatting is possible, and you must perform this "opening" process. ═══ 5. Processing a REXX Source Program ═══ There two actions that are possible on any Open REXX source program: You may format the identified program, or You may edit it. If you have selected labels, variables, or function names to be cross-referenced in the General Settings of the RCF/2 configuration, you may, as a third action, show cross references after a program has been formatted. ═══ 5.1. Formatting ═══ To format an open REXX source program, do the following: 1. Select Action from the RCF/2 main window menu bar. 2. Select Format from the resulting pull-down menu. ═══ 5.2. Formatting Notes ═══ During the formatting process, it is not always possible to format a program according to your configuration specifications. For example, you might have a left-hand comment that is too long to fit within the comment positioning values you have set, or the text of a statement is too long to permit proper alignment of a right-hand comment. Additionally, certain coding errors can also be detected such as a quoted string literal with no ending quote or a comment not closed when an end of file is reached on the input program. If any problem or other formatting condition is experienced during the formatting process, RCF/2 will generate, when the formatting process is complete, a secondary window listing the formatting notes. The illustration below is an example of a program in which a couple of formatting problems were encountered. Note: A REXX Code Formatter/2 Notes window will not be displayed unless there is at least one formatting note. ═══ 5.2.1. Working with Formatting Notes ═══ When the REXX Code Formatter/2 Notes window is displayed, you may close the window or print a list of the notes. You may also review the notes and examine the corresponding output line to which the note refers. If you click on any note, the corresponding formatted output will be highlighted and displayed in the RCF/2 main window. (The first note and its corresponding statement will always be preselected for you.) You will also see, in the upper right-hand corner of the RCF/2 main window, the input record number and output line number associated with this note. If you wish to fix the formatting anomaly, you may invoke the editor, go to the referenced record number, make the desired changes, and reformat the program. ═══ 5.3. Editing ═══ To edit an open REXX source program, do the following: 1. Select Action from the RCF/2 main window menu bar. 2. Select Edit from the resulting pull-down menu. ═══ 5.4. Show Cross References ═══ If you have selected one or more items to be cross referenced in the General Settings section of the configuration settings notebook, you may display the results by doing the following: 1. Select Action from the RCF/2 main window menu bar. 2. Select Show from the resulting pull-down menu. 3. Select Labels X-Ref, Variables X-Ref, or Functions X-Ref from the pull-down menu. ═══ 6. Saving Formatted Results ═══ After a program has been formatted, you may replace the original input with the formatted results, or you may save the formatted version of the input program in another directory or under a different name. To replace the original input file with the formatted version of the file, do the following: 1. Select File from the RCF/2 main window menu bar. 2. Select Save from the resulting pull-down menu. To save the formatted results under an different name or in a different directory, do the following: 1. Select File from the RCF/2 main window menu bar. 2. Select Save As from the resulting pull-down menu. 3. Using the dialog box: Select the directory where the newly formatted program is to be stored, and Modify the name of the program if it is to be different than the one shown. 4. Click on OK to save the formatted program. To replace the original input file with the formatted version of the file and then exit RCF/2, do the following: 1. Select File from the RCF/2 main window menu bar. 2. Select Save & Exit from the resulting pull-down menu. ═══ 7. Printing ═══ After RCF/2 has formatted a program, you may print a listing of that program or any created cross references. To generate hardcopy output of a formatted program or cross references, do the following: 1. Select File from the RCF/2 main window menu bar. 2. Select Print from the resulting pull-down menu. 3. Select Program, Labels x-ref, Variables x-ref, or Functions x-ref from the second pull-down menu. 4. Select Landscape report orientation from the resulting dialog menu if you have selected this type of report using the Program Listing Options. 5. Click on the Print button. Note: The format of the generated listing is controlled by the options defined by the Program Listing Options. ═══ 8. Program Listing Options ═══ RCF/2 allows you to print your formatted program using VisPro/Reports. The generated reports are printed using a mono-spaced Courier font, and you may pick one of two font sizes, 8-point or 10-point, with corresponding lines per inch spacing, depending on your preference. You may also select whether you wish the report to formatted for portrait or landscape orientation. The Print Options allow you to specify which format you prefer for your program listings. Report Format Portrait - 80 Characters per line The form of this report is with Portrait orientation, and it will print up to 80 characters on a single line using a 10-point Courier font. Any formatted record longer than 80 characters will be printed on multiple lines, 80 characters at a time, until the record is printed. Vertically, the output report will be spaced at approximately six lines to the inch. Portrait - 105 Characters per line The form of this report is with Portrait orientation, will print up to 105 characters on a single line using an 8-point Courier font. Any formatted record longer than 105 characters will be printed on multiple lines, 105 characters at a time, until the record is printed. Vertically, the output report will be spaced at approximately eight lines to the inch. Landscape - 110 Characters per line The form of this report is with Landscape orientation, and it will print up to 110 characters on a single line using a 10-point Courier font. Any formatted record longer than 110 characters will be printed on multiple lines, 110 characters at a time, until the record is printed. Vertically, the output report will be spaced at approximately six lines to the inch. Landscape - 180 Characters per line The form of this report is with Landscape orientation, will print up to 180 characters on a single line using an 8-point Courier font. Any formatted record longer than 180 characters will be printed on multiple lines, 180 characters at a time, until the record is printed. Vertically, the output report will be spaced at approximately eight lines to the inch. Date and time format to use on listing All generated reports will be date and time stamped according to when the request for printing occurred. You may select the format for the date and time by selecting the desired value. Use American date format The printed date will be of the form "month day, year." "October 5, 1996" is an example of this form of date-stamp. Use European date format The printed date will be of the form "day month year." "5 October 1996" is an example of this form of date-stamp. Use 12-hour clock When this option is elected, the time shown on the report will be of the form "hh:mm" with the appropriate "am" or "pm" showing. "1:47pm" is an example of this form of time-stamp. Use 24-hour clock When this option is elected, the time shown on the report will be of the form "hh:mm" with the hour (hh) ranging in value from 00 to 23. "13:47" is an example of this form of time-stamp. To close the Print Options window, do one of the following:  Select Okay to save any changes to the Print Options settings.  Select Cancel to cancel any changes made are keep the Print Options settings as they were. ═══ 9. Exiting RCF/2 ═══ You may exit REXX Code Formatter/2 by any of the following methods:  Select File from the RCF/2 main window menu bar and then click on Exit in the resulting pull-down menu.  If the main RCF/2 window is in focus, press F3  Click on the REXX Code Formatter/2 icon in the upper left corner of the main RCF/2 window and select Close from the resulting pull-down menu.  Double click on the REXX Code Formatter/2 icon in the upper left corner of the main RCF/2 window. ═══ 10. Registration ═══ This is a full-function program that is offered as SHAREWARE. Registration fee is $15 U.S. per copy. To register your copy of REXX Code Formatter/2 and receive your Registration Key, order RCF/2 from BMT Micro or RKE Consulting, Inc.. Ordering from RKE Consulting, Inc.. Ordering from BMT Micro. ═══ 10.1. Ordering from RKE Consulting, Inc. ═══ To order from RKE Consulting, Inc., send $15 (plus $1.09 sales tax if you are a resident of Texas) drawn on a U.S. bank to: RKE Consulting, Inc. P.O. Box 11569 Spring, TX 77391-1569 Please indicate whether you would like your Registration Key sent by normal mail (i.e., snail-mail) or E-mail, and include the address to be used. To order by credit card, please send your orders to BMT Micro. ═══ 10.2. Ordering from BMT Micro ═══ To order from BMT Micro, use the following BMT Micro ordering information: Mail Orders To: BMT Micro PO Box 15016 Wilmington, NC 28408 U.S.A. Voice Orders: 8:00am - 7:00pm EST (-5 GMT) (800) 414-4268 (orders only) (910) 791-7052 Fax Orders: (910) 350-2937 24 hours / 7 Days (800) 346-1672 24 hours / 7 Days Online Orders via modem: (910) 350-8061 10 lines, all 14.4K (910) 799-0923 Direct 28.8K line Ordering and general ordering questions: Via AOL: bmtmicro via MSN: bmtmicro Via Prodigy: HNGP66D via Compuserve: 74031,307 via Internet: orders@bmtmicro.com telnet@bmtmicro.com http://www.bmtmicro.com We accept Visa, Mastercard, Discover, American Express, Diners Club, Carte Blanche, Cashiers Check, Personal Check. Personal checks are subject to clearance. Eurochecks in DM are welcome. DM, Sterling, and US Currency is welcome but send only by registered mail, return receipt requested. We cannot be liable for lost cash sent through the mail. Purchase orders are welcome, subject to approval. The minimum amount is $250.00. Information for our German customers is explained in the last paragraph of this order form. _____________________________________________________________________ Company:_____________________________________________________________ Name:________________________________________________________________ Address:_____________________________________________________________ _____________________________________________________________ City: _______________________________State/Province: ________________ Postal/ZIP Code: ____________________Country:________________________ Phone:_______________________________________________________________ Fax: _______________________________________________________________ E-Mail #1____________________________________________________________ E-Mail #2____________________________________________________________ Product Quantity Price Number of copies _________________________ ______________ ________________ _________________________ ______________ x ____________ = + $ _______ _________________________ ______________ x ____________ = + $ _______ _________________________ ______________ x ____________ = + $ _______ Latest Version on Diskette _____$3.00____ x ____________ = + $ _______ North Carolina Residents add 6% Sales Tax $ _______ Shipping and Handling (no quantity limit / see below) $ _______ Email - Subject to Credit Card Verification Free Fax (USA/Canada)........................... 1.00 US Fax (Non-North America).................... 2.00 US Worldwide 1st Class ....................... Free 2nd Day Priority, USA Only ................ $ 4.00 US US Postal Service International Express (Including Canada and Mexico), allow up to 7-10 days ............................... $ 25.00 US Airborne Select Delivery (USA Only) $ 8.00 US FedEx Overnight, USA Only (delivery by 3:00 pm the following day) .............. $ 15.00 US FedEx Europe/Japan (guaranteed delivery within 3 days) .......................... $ 35.00 US Total: $ _______ ┌───────────────────────────────────────────────────────────────────┐ │ │ │ For credit card payment only │ │ │ │ Circle one: VISA / Master / Discover / American Express / Diners │ │ │ │ Credit card number: _____________________________________________ │ │ │ │ Expiration date: ________________________________________________ │ │ │ │ Authorization signature: ________________________________________ │ │ │ └───────────────────────────────────────────────────────────────────┘ ORDERING FROM INSIDE GERMANY ONLY ================================= Persons in Germany wishing to order shareware may also transfer funds into our account with Deutsche Bank. Once the money is deposited you may either fax a confirmation to us with proof of deposit or wait until Deutsche Bank notifies us of the transaction (usually 10-18 business days). Account information is as follows: Deutsche Bank / Frankfurt Branch EmpfДnger: Thomas Bradford / BMT Micro Konto-Nummer: 0860221 Bankleitzahl: 500-700-10 When you make the transfer, be sure to put your name and the program you are registering on the transfer. Current exchange rates can be obtained by sending an email to dm_to_us@bmtmicro.com. An automated reply will return todays exchange rates. It is very important that you send us a completed order form by either email or fax if you deposit money into this account for a registration. Fill the order form out as usual except in the credit card number field put "DEUTSCHE BANK". We will file the order and use it to match against the deposit information we receive from the bank. IMPORTANT! ---------- When you email us your order form, we will reply with an acknowledgement. If you do not get an acknowledgement within 24 hours please send your order again in case it was lost. This extra bit of caution can save a lot of confusion. If you are concerned that your order is taking too long to process, feel free to check with us about the status of your order. It's important to all of us that you feel safe doing business with our company and please feel free to suggest ways we can improve our service to you. ═══ ═══ VisPro/REXX is a trademark of HockWare, Inc. ═══ ═══ VisPro/Reports is a trademark of HockWare, Inc. ═══ ═══ The Save option saves the current settings of the configuration notebook so that the settings will be used when returning to the main RCF/2 window, and they will be used on all future invocations of RCF/2. ═══ ═══ The Exit option saves the current settings of the configuration notebook, but any changes to the configuration will be discarded when leaving RCF/2. To permanently save any changes to the configuration notebook, use the Save menu option. ═══ ═══ The Cancel option terminates the configuration notebook and discards any changes made to the configuration. ═══ ═══ Labelled routines within a program are internal functions when invoked by a call to that routine. RCF/2 will format such calls according to the configured rules for function name formatting. ═══ ═══ The only exception to this is the first record of input. OS/2 requires that the slash-asterisk in the first record, which must always begin with a comment, start in column one. If it does not, RCF/2 will left justify the comment and notify you that this change has been made. ═══ ═══ The current indentation is the indentation actually in effect based on the open Do and Select statements, the general indentation, and so forth. ═══ ═══ Even if you do not modify the program, you may wish to reformat after generating an Associated Label File as described under Label Names Formatting. ═══ ═══ This is the main REXX Code Formatter/2 window. All the facilities of RCF/2 are available using the menu bar, and all formatting actions performed are reflected in the body of the window. ═══ ═══ This is the body of the REXX Code Formatter/2 window. When formatting occurs, this part of the display will show the results of the formatting action. ═══ ═══ The name of the "opened" program file appears here. Any Format or Edit action will process the file named in this area of the window. If no name is shown, no REXX source file is currently defined to RCF/2, and formatting is not possible. ═══ ═══ The two numbers displayed here show the number of the input and output statements associated with the currently selected (highlighted) line in the body of the display. The first number is the number of the input record used partially or entirely to generate this line of output, and the second number is the output line number. Any formatting notes will always reference the output line number. ═══ ═══ The menu bar is used to initiate some facility of RCF/2. Using the options on this bar you may: Select File to:  Identify the REXX source program to be processed,  Save or Print the formatted results, or  Exit REXX Code Formatter/2. Select Configure to:  Define the style to be used for formatting, and  Identify an editor to be used if needed. Select Action to:  Format a REXX program,  Edit a REXX program, or  Show cross-reference information. Select Help to:  View this help information,  Display product information, or  Register RCF/2. ═══ ═══ If the notes window is in the way, you can simply drag it to one side to examine the statement of interest. ═══ ═══ To close the REXX Code Formatter/2 Notes window, click on the Exit option of its menu bar. ═══ ═══ To print a listing of the generated notes, click on the Print option of the REXX Code Formatter/2 Notes menu